Walkthrough

The changes extend the per-request context manager to capture and propagate docket and worker context via ContextVars, enabling dependency injection for these resources across async context boundaries. A new internal worker reference is added to the FastMCP server instance and populated during the docket lifecycle. A guard is also introduced to the lifespan manager to prevent re-entrance. Error messages are updated to reference the broader server context requirement, and logging in subscription handlers is adjusted from warning to error level.

Possibly related PRs

• Make pydocket optional and unify DI systems #2835: Modifies the same context/lifespan code paths by adding/using _current_docket and _current_worker ContextVars and adjusting server/docket lifespan to set/reset those tokens, making it directly related at the code level.
• Remove enable_docket setting; Docket is now always on #2558: Modifies the server lifecycle and ContextVar-based docket/worker context management, sharing the same server/context lifecycle and worker/docket management code paths.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Test Failure Analysis

Summary: Test (line 572 in ) is timing out after 5 seconds on Windows (Python 3.10).

Root Cause: The PR changes to remove the background notification flusher ( task) that was running in a task group. This background task was responsible for periodically flushing notifications during long-running operations.

The timeout is happening because:

1. The test spawns stdio subprocesses (Python servers) that need to communicate with the client
2. The removed background flusher was handling periodic notification flushes during these long operations
3. Without it, the test may be hanging waiting for notifications or responses that aren't being properly flushed

Detailed Analysis:

In src/fastmcp/server/context.py:

• Before: __aenter__ created a task group and started _periodic_flush in the background
• After: The task group and background flusher are removed entirely
• The PR only flushes notifications on __aexit__, which may be too late for multi-server stdio scenarios

# REMOVED:
self._exit_stack = AsyncExitStack()
await self._exit_stack.__aenter__()
tg = await self._exit_stack.enter_async_context(anyio.create_task_group())
self._cancel_scope = anyio.CancelScope()
tg.start_soon(self._periodic_flush)

Suggested Solution:

The ContextVar fix (setting _current_docket and _current_worker from server instance) is correct for the ASGI issue. However, you need to restore some form of periodic flushing for stdio transport scenarios. Options:

1. Keep the background flusher but make it conditional - only start it when not in ASGI/serverless environments
2. Manual flush points - Add explicit flush calls at key points in the stdio transport/client code
3. Different approach - Consider if notifications need to be flushed differently for stdio vs HTTP transports

Related Files:

• src/fastmcp/server/context.py (lines 162-210) - Context lifecycle changes
• tests/test_mcp_config.py (line 572) - Failing test
• Issue Background tasks fail with 'require a running FastMCP server context' when using http_app() mounted to FastAPI #2671 - The ASGI ContextVar propagation issue this PR fixes

pytestmark = pytest.mark.skipif(
    sys.platform.startswith("win32"),
    reason="Windows has process lifecycle issues with stdio subprocesses",
)

Test Failure Analysis

Summary: Test test_multi_client_with_transforms (line 572 in tests/test_mcp_config.py) is timing out after 5 seconds on Windows (Python 3.10).

Root Cause: The PR changes Context.__aenter__ to remove the background notification flusher (_periodic_flush task) that was running in a task group. This background task was responsible for periodically flushing notifications during long-running operations.

The timeout is happening because:

1. The test spawns stdio subprocesses (Python servers) that need to communicate with the client
2. The removed background flusher was handling periodic notification flushes during these long operations
3. Without it, the test may be hanging waiting for notifications or responses that aren't being properly flushed

Detailed Analysis:

In src/fastmcp/server/context.py:

• Before: __aenter__ created a task group and started _periodic_flush in the background
• After: The task group and background flusher are removed entirely
• The PR only flushes notifications on __aexit__, which may be too late for multi-server stdio scenarios

# REMOVED:
self._exit_stack = AsyncExitStack()
await self._exit_stack.__aenter__()
tg = await self._exit_stack.enter_async_context(anyio.create_task_group())
self._cancel_scope = anyio.CancelScope()
tg.start_soon(self._periodic_flush)

Suggested Solution:

The ContextVar fix (setting _current_docket and _current_worker from server instance) is correct for the ASGI issue. However, you need to restore some form of periodic flushing for stdio transport scenarios. Options:

1. Keep the background flusher but make it conditional - only start it when not in ASGI/serverless environments
2. Manual flush points - Add explicit flush calls at key points in the stdio transport/client code
3. Different approach - Consider if notifications need to be flushed differently for stdio vs HTTP transports

Related Files:

• src/fastmcp/server/context.py (lines 162-210) - Context lifecycle changes
• tests/test_mcp_config.py (line 572) - Failing test
• Issue Background tasks fail with 'require a running FastMCP server context' when using http_app() mounted to FastAPI #2671 - The ASGI ContextVar propagation issue this PR fixes

pytestmark = pytest.mark.skipif(
    sys.platform.startswith("win32"),
    reason="Windows has process lifecycle issues with stdio subprocesses",
)

Update: Additional Finding

I discovered something important - the test should not be running on Windows at all!

The test file tests/test_mcp_config.py has this marker at the top (line 42):

pytestmark = pytest.mark.skipif(
    sys.platform.startswith("win32"),
    reason="Windows has process lifecycle issues with stdio subprocesses",
)

This should skip ALL tests in that file on Windows, but the tests are clearly running (they're passing up until the timeout).

This means:

1. Either the skipif condition is not working correctly
2. OR sys.platform is not returning "win32" on the Windows CI runner

Let me investigate the actual platform string on Windows GitHub Actions runners...

Actually, looking at Python docs: on Windows, sys.platform returns "win32" even on 64-bit Windows. So the condition should work.

Hypothesis: The skipif might be evaluated at collection time with the wrong environment, or there's been a change in how pytest handles module-level pytestmark in recent versions.

Immediate Fix:
Rather than debugging the marker issue, you could add a @pytest.mark.skipif(sys.platform.startswith("win32"), ...) decorator directly to the failing test test_multi_client_with_transforms as a workaround. But the root cause (background flusher removal) still needs to be addressed.